MacHack 1994/MacHack 1994.toast/MacHack™ 1987-1994/MacHack™ '87/Source ƒ.sea/Source ƒ/Pascal ƒ/Pascal utils/Utility Documentation/Utility Documentation

Text File | 1986-12-09 | 14.1 KB | 339 lines | [TEXT/QED1]

    The Following is the Interface part of a Utilities Unit written by
David O'Rourke.  The purpose is to provide some general utilities that will
enhance the uses of standard ROM calles.  None of the routines are very complex
but they are useful and have a standard interface that was thought out with
some care.  I hope you find them useful.

unit Utilities;

interface

    const
        {Useful MacConstants}
        DefaultItem   = 1;
        Margin5       = 5;
        Margin16      = 16;
        ScrollBarSize = 16;
        Window_Title  = 18;
        MenuBarSize   = 20;
        NewRomsID     = 117;
        DeadControl   = 255;
        TESelStart    = 0;
        TESelEnd      = 32767;
        TooMuch       = 16777216;

        {Useful Mac Key code constants.  ASCII codes}
        ETX                    = $03;    {Enter Key}
        EnterKey        = ETX;
        BS                    = $08;    {BackSpace Key}
        CR                    = $0D;    {Return Key}
        ReturnKey        = CR;
        HT                    = $09;    {TAB Key}
        TabKey            =    HT;
        ESC                    =    $1B;    {Escape Key}
        FS                    =    $1C;    {Left arrow key}
        LeftArrow        =    FS;
        GS                    =    $1D;    {Right arrow key}
        RightArrow    = GS;
        RS                    =    $1E;    {Up arrow key}
        UpArrow            =    RS;
        US                    =    $1F;    {Down arrow key}
        DownArrow        = US;
        EndofLine        = $7F;    {End of Line Delimeter}
        NoBrkSpace    = $CA;    {None Breaking space for Mono Spacing}

      {Utility Dialog Constants}
      YesNoCancelID = 1966;
          YesButton         = 1;
          CancelButton    =    2;
          NoButton            =    3;
          StaticText        =    4;

    type
        GenericResponse = (nullResponse, YesResponse, CancelResponse, NoResponse);

    var
      theDialogFilter    : ProcPtr;    {A Pointer to the Dialog Filter Procedure}
      ScreenSize            :    Rect;            {A Global constant containing the screen size}

    procedure StandardInit;

    function GetEven (theNum: LONGINT): LONGINT;
    function GetRectSize (theRect: Rect): Point;
    function NewRoms: BOOLEAN;
    function HFSRunning: BOOLEAN;
    function OptKeyDown     (theModifiers: INTEGER): BOOLEAN;
    function CapsLockDown (theModifiers: INTEGER): BOOLEAN;
    function ShiftKeyDown    (theModifiers: INTEGER): BOOLEAN;
    function CmdKeyDown     (theModifiers: INTEGER): BOOLEAN;
    function WindowActivate (theModifiers: INTEGER): BOOLEAN;

    procedure CenterInRect (VAR theRect: Rect; theCenterRect: Rect;
                            vOffSet, hOffSet: INTEGER);
    procedure CenterInScreen (VAR theRect: Rect; vOffSet, hOffSet: INTEGER);

    function GetWindowKind (theWindow: WindowPtr): INTEGER;
    function FrontSysWindow: BOOLEAN;
    function CenterNewWindow (theWindowID: INTEGER; wStorage: Ptr;
                              behind: WindowPtr; vOffSet, hOffSet: INTEGER): WindowPtr;

    procedure ToggleButton (theControl: ControlHandle);

  function  DoSFGet (theFileCount: INTEGER; theTypeList: SFTypeList;
                      vOffSet, hOffSet: INTEGER): SFReply;
    function  DoSFPut (theSavePrompt, OrigFileName: str255;
                        vOffSet, hOffSet: INTEGER): SFReply;

    function CenterNewDialog (theDialogID: INTEGER; dStorage: Ptr;
                              behind: WindowPtr; vOffSet, hOffSet: INTEGER): DialogPtr;
    procedure OutLineButton (thePort: GrafPtr; theRect: Rect);
    procedure DialogDefault (theDialog: DialogPtr);
    function  DialogFilter (theDialog: DialogPtr; VAR theEvent: EventRecord;
                                                   VAR theItem: INTEGER): BOOLEAN;
    procedure SetupDialog (theDialog: DialogPtr;
                            ButtonKeys, CheckBoxKeys, RadioKeys: BOOLEAN);
    procedure DisposSetUp (theDialog: DialogPtr);
    function GetDLOGRefCon (theDialog: DialogPtr): LONGINT;
    function YesNoCancelDLOG (parm0, parm1, parm2, parm3: str255): GenericResponse;


Instructions:::

Constants:
    The constants can be used any way that the programmer sees fit.  Here is a list
of some of the more useful ones for Macintosh Programming.

DefaultItem:    this is simply the number one but that is also the Item that
                            modalDialog returns when the return or enter key is hit. Therefore
                            this is useful for comparisions after calling ModalDialog.
ScrollBarSize:    This constant is the number of pixels wide (or tall) of a ScrollBar
Window_Title:    This is the height (in pixels) of a standard window title bar.
MenuBarSize:    This is the height (in pixels) of the standard Menu Bar.
DeadControl:    This is the value you pass to HiliteControl to disable a control.
TESelStart,
TESelEnd:    This two constants together will select all of the text in any
                    TE Edit record when passed in the proper parameters.
YesNoCancelID:    This is the resource ID of the Yes/No/Cancel Dialog provided by
                                the Utility Unit.

StandardInit:
    This procedure calls ALL possible Init procedures in the Macintosh.  In
addition to calling the init routines it installs a procedure that enables the
resume button in the system error box that will take you back to the Finder.
NOTE:    This init procedure assumes you are running under System 3.2 and
            Finder 5.3 or later

GetEven:
    Given a LONGINT this function returns the NEXT even number if the number is
ODD.  This is useful for macintosh programing since all addresses have to be
on even word boundries.

GetRectSize:
    Given a rectangle this function returns the width and height of the rectangle
in a Point.  Where Point.v = height and Point.h = width.

NewRoms:
    If this function returns true you are currently running on a machine that has
the New 128K ROMS installed.

HFSRunning:
    If this function returns true you are currently running on a machine that has
the HFS filing system currently active.
NOTE: This doesn't mean you also have the new ROMS since HFS can be loaded into
            RAM at boot time.

OptKeyDown,
CapsLockDown,
ShiftKeyDown,
CmdKeyDown,
WindowActivate:
    Given the modifiers field from an eventRecord this routines return TRUE if
the Keys that are abreviated where down when the event was posted.  In the case
of WindowActivate the routine returns TRUE if the Activate bit was set by an
Update event.

CenterInRect:
    Given two rectangles and a vertical and horizontal offset, this routine will
center the first rectangle in the second rectangle, and then offset the
now centered first rectangle by the requested amount.  The centered and then
offset rectangle is then passed backout in the first parameter.
    The offsets can be either positive or negitive.  Two positive parameters
indicate an offset down and to the right, negitive ='s up and to the left. This
is in keeping with the way quickdraw does it's relative offsets.  If no offset
is desired simply pass 0 as the arguments.
NOTE: This routine was written assuming that the first rectangle would be
            smaller than the second rectangle.  The results will be wrong if this
            is not true.

CenterInScreen:
    Given a rectangle and a vertical and horizontal offset this routine behaves
exactly like the one above except it will automaticly center the rectangle in
the current screen without the MenuBar.  The rectangle will not be
centered in the screen, but it will be centered in the screen between the
bottom of the menubar to the bottom of the screen.  The normal desktop region
that is the gray pattern.

GetWindowKind:
    Given a windowPtr this routine returns the windowKind field of the windowrecord
This is useful for checking if a wind is a deskaccessory.

FrontSysWindow:
    This function returns TRUE if the frontmost window is a Desk Accessory.

CenterNewWindow:
    This function is exactly the same a GetNewWindow, except it also centers the
window, (by calling CenterInScreen), and then shows it.  Show if you window template
was invisible this routine would recall it from the resource file, center it
and then show it.
    I have added two additional parameters to this function that are the vertical
and horizontal offsets for after the window is centered.
NOTE:    This routine uses the window's portrect as the rectangle that is centered
            this is fine for most windows but not a standard document window.  The
            portrect of a standard document window doesn't include the title bar size
            as part of the portrect.  So even thought the portrect will be centered
            the window itself might not be.  If this is a problem simply pass the
            constant Window_Title as the vertical offset.

ToggleButton:
    Given a handle to a control this routine toggles the hilighting between one and
zero.  If it's one it changes to zero, and if it zero it changes it to one.
This routine is particulary useful for turning radio buttons and checkboxes on
and off, and makes it so the code doesn't have to keep track of the buttons
hilite state.  Because if you call it will the last control it will turn it
off and then call it with the new control and it will then turn that one on.
All the programer has to do is keep track of the last control he turned on and
the new control that needs to be turned on.

DoSFGet:
    Given a file type count, the file type list and a vertical and horzontal
offset.  This function automaticly puts up and centers the Standard File open
Dialog and returns an SFReply that is the file choosen by the user.
    For more information on the file type count and the file type list and the
SFReply record see inside macintosh Vol. I chapter 20.

DoSFPut
    Given a save file prompt and the original string and a vertical and horizontal
offset.  This function automaticly puts up and centers the Standard File save
Dialog and returns an SFReply that is the save file choosen by the user.
    For more information on theSavePrompt, OrigFileName and SFReply record see
inside macintosh Vol. I chapter 20.

CenterNewDialog:
    This function is identical to GetNewDialog and it behaves exactly like
CenterNewWindow, except that this routine is for Dialogs.  The parameters,
(except for the vertical and horizontal offsets), are identical to the
GetNewDialog parameters.
    This function gets the dialog, centers it in the current screen and then
shows it show if your dialog template is invisible the user won't see all of
the movement on the screen.

OutLineButton:
    Given a GrafPtr and a rectangle this routine outlines, or bolds, the rectangle
with the standard bold outline for buttons.

DialogDefault:
    Given a DialogPtr this routine automaticly outlines, or bolds, the default
item with the standard macintosh bold outline.

DialogFilter:
    This is a filter provided as a "new" standard filter procedure for Modal Dialogs
After the neccessary setup procedures have been called, by passing a procedure pointer
(theDialogFilter) to modal Dialog this filter will execute.
    If the user hits return or enter the default Item is returned as hit, this
is no different than the standard macintosh dialog filter.
    If the user double clicks on a radio button the filter first returns the
radio button item number and then returns the default item as hit if the second
click was in the double click time period and the click occured on the same item.
This is useful so the use can double click on a radio button and dismiss the
Dialog in one simple double click.
    It also montiors command-key events and maps them onto the the appropriate
Item numbers.  You can have command key equivilants for buttons, check boxes,
and radio buttons.  The first character in the buttons Title determines it's
keyboard equivilant.  If the buttons title was "Red" the command-R would cause
the filter procedure to return as though the mouse was clicked on the button
red.
NOTES:
    1)    This routine uses some new ROM calls and will crash if executed on an old
            machine.  But the Filter checks to see if it is on an old machine and
            disables itself calling the standard ModalDialog filter procedure if it
            is running on an old machine.
    2)    The call to use this filter goes something like this

                theDialog := GetNewDialog(...);
                SetUpDialog(theDialog, TRUE, TRUE, TRUE);  {more on this later}

                while somecondition
                    ModalDialog(theDialogFilter, ItemHIT);
                    ....
                    ....
                    ....
                end;    {while somecondition}

                DisposSetUp(theDialog);
                DisposDialog(theDialog);

            Notice the global variable theDialogFilter is used.  Please don't set
            this value yourself, it is set for you every time SetupDialog is called
            and is set properly depending on if the new ROMS are present.

            This call will work on all macintosh's, but on the older one the features
            of this filter are simply disabled.

            Notice the SetUpDialog and DispoSetUp call, these calls are necessary to
            setup some data structures for the filter to use.  DisposSetup simply
            removes the temporary data structures created by SetupDialog.

SetUpDialog:
    Call this procedure before calling modal dialog with myFilter.  The four
parameters are as follows, the DialogPtr that is the dialog to be setup and
the booleans indicating the type of buttons to have keyboard equivilants
assigned to them.  By passing true to these parameters tells the setup to
assign a keyboard equivilant to that type of button, false tells the procedure
to ignore that type of button when setting up the keyboard map.
    In the event that two, or more, buttons have the same first character in
their titles only the first occurence is used and all others are ignored.

DisposSetUp:
    Call this routine when you are done with theDialog and want to free up the
memory allocated by SetupDialog.

GetDLOGRefCon:
    I use the refCon to hold the handle pointing to my data structures so after
calling SetUpDialog, you must you this call to retreive you RefCon that you
stored in the Dialog.  After calling disposSetup the RefCon is restored and
you can use the normal tool box calls to get at it.

YesNoCancelDLOG:
    This displays the standard YES/NO/Cancel DLOG as outlined by Inside Macintosh
Volume IV for use when asking the user a question such as
"Save Changes Before Quitting".  It takes four parameters which determine the
message that is displayed to the user and returns and value of type GenericResponse
which you program can then respond to.
    It automaticly centers the dialog, outlines the default response, and uses
my filter for ModalDialog with keyboard equivilants for each of the three
buttons.  A sample call might be as follows

    FileName := 'Test Data';
    ActionStr := 'Quitting??';

    {the message displayed to the user would be
            'Save changes to Test Data before Quitting??'}

    theResponse := YesNoCancelDLOG('Save changes to ', FileName, ' before ', ActionStr);
    case theResponse of
        YesResponse : begin
                                        DoSave(...);
                                        Closewindow(...);
                                        ...
                                    end;
        NoResponse : begin
                                    CloseWindow(...);
                                    ....
                                    end.
        CancelResponse: your choice of code
    end;    {case}

    Have fun and I hope you find the utilities useful, I'm open to ideas and
questions.

David O'Rourke